Software 2000

home *** CD-ROM | disk | FTP | other *** search

/ Software 2000 / Software 2000 Volume 1 (Disc 1 of 2).iso / utilities / u265.dms / in.adf / ConMan / ConMan.Doc / ConMan.Doc

Wrap

Text File | 1992-04-11 | 24.3 KB | 461 lines

ConMan V1.3 Revision 2 Copyright (c) 1987, 1988 by William S. Hawes ConMan is a replacement console handler that provides line editing and command history for any software that uses CON: windows. It runs under AmigaDOS V1.2 and later, and is completely transparent to other software. After ConMan has been activated, all CON: windows opened by AmigaDOS will automatically use the ConMan handler. This includes the console windows opened by NEWCLI as well as any data input/output windows that your other software may use. Features new to ConMan V1.3 include the CND: handler for invisible, non-blocking type-ahead, the CNX: (extensible) handler for use of the serial device as a console, improved editing of long lines, and support for superbitmap windows. As was the case with prior releases, ConMan is distributed as shareware (user-supported software), and I'm pleased to report that the rate of contributions has increased since that last release. Shareware is a welcome alternative to the high costs of commercial software, and I hope that you'll do your part to support ConMan and other shareware products. ----- Line Editing ----- ConMan allows you to edit the active (command) line using the left- and right-arrow keys for cursor positioning. The shifted left-arrow key skips to the beginning of the current or previous word, and the shifted right-arrow key skips to the start of the next word. ConMan supports both insert and overstrike editing modes. The CTRL-A key toggles between the two modes, and the CTRL-^ key unconditionally selects insert mode. The default input mode is insert, but you can set the global -o flag to select overstrike mode. The input mode normally reverts to the default mode each time you press RETURN, but the global -s ("sticky") flag will cause the mode to remain set until you change it explicitly. You can select insert or overstrike mode when you first install ConMan, and can change it at any time using the SetCMan command utility. Try experimenting to see which input mode you like best, but note that the input modes are global and therefore apply to ALL ConMan windows. Refer to the paragraph on installation for a list of the global option flags. There are several keys that can be used to delete characters, words, or the entire line. The DEL key deletes the character under the cursor, and the BACKSPACE key deletes the character to the left of the cursor. CTRL-Y deletes from the cursor position to the end of the line, and CTRL-U deletes from the cursor to the start of the line. CTRL-X deletes the entire line, in keeping with the default CON: device. Function keys F7 and F8 can be used to delete words in the backwards and forwards direction, respectively. They work just like the shifted left- and right-arrow keys except that the characters are deleted. CTRL-Z deletes both the current line and any lines that have been typed ahead (but not yet read); this is very handy if you want to completely abandon all typed-ahead lines. CTRL-R provides a less drastic recall by posting the typed-ahead lines back to the command line. CTRL-W clears the entire window and then redisplays the active line. The Undo Buffer. Suppose that you're editing a line and you accidentally hit the up- or down-arrow key. You've just lost the line, right? Not at all --- just press the CTRL-- (control-minus) key and the former line will be posted back to the command line, with the cursor right where you left it! There is no limit to the number of lines that can be undone, but only lines that have been changed are added to the undo buffer. All "undo" lines are discarded when you finally enter RETURN. Flow Control. CTRL-S and CTRL-Q have been implemented to hold and release the screen output, respectively. After pressing the CTRL-S key, all output to the window will be held until you release it with a CTRL-Q. ConMan will now (as of revision 2) "beep" the display if you try to type with CTRL-S in effect, in order to provide some visual indication that output is held. End-of-File. ConMan recognizes the CTRL-\ character as an end-of-file and sends a zero-length block to the task reading from the handler. CTRL-\ can be used to terminate a copy operation. All characters not explicitly required for editing purposes are passed on to the command line. In order to provide a consistent display, characters that might cause interference with the display (like CTRL-L) are rendered as a caret (^) followed by the uppercase alphabetic character. The CTRL-N (shift-in) and CTRL-O (shift-out) characters are supported by ConMan; these are non-printable by themselves, but serve to select and unselect the alternate character set. Miscellaneous non-printable characters are displayed as a hash mark. ConMan now allows control sequences can be entered incrementally. For example, entering ESC, [, 0, and ~ will simulate the effect of an F1 key. ----- Command History ----- ConMan "remembers" the commands that you type and lets you recall them sequentially using the up- and down-arrow keys. If you go past the line you want, the down-arrow key will retrieve the next (more recent) line. The shifted up-arrow key recalls the oldest line, and shifted down-arrow recalls the most recent line. The CTRL-B key clears the history buffer. The history buffer is organized as a fixed-length memory pool with a default length of 488 bytes. New lines are inserted at one end, and the oldest lines are "pushed off" the other end to make room. The number of lines that can be saved depends on their lengths, but is generally in the range of 25 to 30. The default size can be changed when you install ConMan by using the -b option followed by the desired size in bytes. For example, the command "conman -c -b1000" installs ConMan with a 1000-byte history buffer. ConMan maintains the history in one of two modes. In the default mode, recalled lines are not reentered into the history buffer unless the line was "touched," and the history index pointer is left positioned at the retrieved line. This mode is convenient if you often go back into the buffer to retrieve sequences of commands. In "true history" mode, every line is reentered into the history buffer, even if it wasn't modified after being recalled. The history pointer is always reset (to the most recent line) whenever a line is added to the buffer. The history mode can be selected when ConMan is installed or by using the SetCMan utility. Note that ConMan now checks for duplicate entries irrespective of whether standard or "true" history is selected. If the current line matches the previous line entered, the line is not reentered. Minimum Line Length. You can define a minimum line length to be saved in the history buffer by using the -LNNN option. The number following the -L is the limit at or below which lines will not be saved; the default value is 0. For example, "conman -c -L2" will ignore lines of 2 or fewer characters. Wrap-Around History. If you prefer to maintain the command history as a circular buffer rather than as a stack, try setting the -wrap option with ConMan or SetCMan. The index will "wrap-around" when it hits the top or bottom of the stack. Versions 1.1 and later of ConMan include a command called "History" to save, load, or display the history buffer. Refer to the "history.doc" file for more information. ----- Function Keys ----- ConMan has several additional editing functions and window control options that use the function keys. Key F1 shrinks ("iconifies") the window to its minimum size, and key F2 "zooms" the window to its maximum size (usually the entire screen.) Both keys act as toggles, and shrunken windows may be zoomed (and vice-versa.) ConMan V1.3 provides a minor enhancement to the zoom feature: if the window is not exactly at the top of the screen when F2 is hit, it will be positioned one pixel down from the top, rather than right at the top. This allows you to slide the screen even if the window covers most of it. If the window was opened without a sizing gadget, neither F1 or F2 will have any effect. Keys F5 and F6 are used to search for commands. If you type a partial command line and then press F6, ConMan searches in the up-arrow direction for a line matching up to the cursor position. You can move the cursor to the right to constrain the search. Key F5 works similarly in the down-arrow direction. Keys F7 and F8 delete words in the backwards and forwards direction. They operate just like the shifted left- and right-arrow keys except that the words are deleted rather than just skipped over. Function key F9 moves the screen to the front or back of the display, and F10 moves the window to the front or back. Both keys act as toggles provided that you don't deactivate the window or screen. These keys are useful when you're working with multiple windows or screens and need to peek at the one in back. ----- Window Definitions ----- ConMan accepts the standard AmigaDOS window specifications. For example, "CON:160/50/320/100/MyWindow" specifies a window 320x100 pixels in size, beginning in position (160,50). The numeric parameters are truncated against the maximum screen size, so a larger-than-normal window may be safely specified (for those of you using "morerows"). The default size is the full screen width and height. ConMan sets the minimum window size to allow room for the close gadget and depth gadgets. Various Intuition options and gadgets can be selected by including a list of attributes after the window title. Here's how it works: put another slash ("/") after the window title, and follow it with any of the attribute options listed below. Option Character Default Value ---------------- ------------- A <==> Activate Activated B <==> BackDrop Not a backdrop C <==> Close gadget No close gadget D <==> Depth gadgets Depth gadgets M <==> Move (drag) gadget Drag gadget N <==> NoBorder Border (sorry, "B" was used) R <==> Refresh (SMART/SIMPLE) Smart refresh S <==> Sizing gadget Sizing gadget Z <==> Zero-Zero Not a GZZ Each option character will TOGGLE the corresponding window attribute, so if you include an option twice, it will cancel the effect. Any unrecognized attribute characters are ignored, and the closing slash is optional. My apologies to those who wanted a slash in the title. Examples: CON:10/10/300/100/Behind/nb/ a borderless backdrop window. CON:10/10/300/100/Fixed/acm a nonactivated window, with a close gadget, that won't budge. You can select the colors for the window's titlebar area by appending a '/' to the attribute list and specifying the "detail pen" and "block pen" color values; the color numbers are listed below. Pen Number Color ---------- ----- 0 Blue 1 White 2 Black 3 Red For example, "CON://640/100/Colors!/ac/23" would specify a window with black letters (the detail pen) on a red titlebar (the block pen). ----- Installation ---- To install ConMan you'll need to copy a few files to your system disk, but don't worry --- they're all small. Install the file "Conhandler" (184 bytes) in your L: directory, to keep those bigger handlers company. Then copy the file "conhandler.library" (6612 bytes) into your LIBS: directory. Now copy the commands "ConMan", "SetCMan", and "History" to your C: directory; the other command programs are optional. The included "ExecuteMe" file will handle the installation for you if you'd rather do it automatically. If you received ConMan in the form of an ARCed file, first deARC it and then rename "conlib.lib" to "conhandler.library", or use the provided "ARCInstall" script to copy the files. Once these files have been installed, issue the command "conman -c" to activate the handler. After you've activated ConMan, open a CLI window using NEWCLI and check to make sure that the new window has line editing and command history. Once everything is working properly, you should place the "conman -c" command in your startup-sequence so that it's always available. NOTE: ConMan affects only those windows opened AFTER you activate it! It would be very impolite indeed to pull the old handler out from under the existing console windows. You can specify several command line arguments with the ConMan command: Code Action ------ ------ -bNNNN select buffer size NNNN bytes -c install as CON: (the default) -d disable control-C break on write -lNNN minimum length to save -o select overstrike mode -r install as RAW: -s select "sticky" mode -t maintain "true history" -w select "wrap-around" history These command options can appear in any order and remain in effect until you reboot the computer. The -q option used in previous releases is now obsolete, as ConMan writes its copyright to standard output by default. A separate utility program called "SetCMan" has been provided to modify or display the global options. You can use SetCMan to change the -o, -s, -t, or -w options at any time. Examples: setcman ? setcman -o -s -t If you usually operate from WorkBench and only occasionally need a CLI, you can activate ConMan by using the icons. First double-click on the "LoadLib" icon to load the conhandler library, and then activate ConMan by double-clicking the "ConMan" icon. The next CLI you open should now have the line editing and command history provided by ConMan. ----- Distribution ----- This program is distributed as shareware (user-supported software) to Amigoid life-forms everywhere! Make sure your friends get a copy. Your contributions are greatly appreciated and will help me maintain ConMan as well as develop new products. Send all correspondence to: By Mail: By Telephone or EMail: ----------------- ------------------------------ William S. Hawes Phone: (508) 568-8695 P.O. Box 308 BIX: whawes Maynard, MA 01754 CIS: 72230,267 USA PLINK: whawes USENET: hawes@dino.ulowell.edu The suggested contribution is $10 (based on an earlier survey), but any amount is welcome. The number of registered ConMan users has increased significantly since the last release, but is still far below what would be expected for a comparable commercial product. Commercial vendors are welcome to include ConMan with their products, provided that it's noted as being shareware and that the documentation accompanies the software. ----- Other Products ----- I have a couple of other products available commercially. ARexx and WShell can be found at better dealers**, or you can order them directly from me at the above address. ARexx is a multitasking implementation of the REXX language, a high-level interpreted language designed for macro-processing. ARexx has become the de facto standard for inter-program communications and can be used as the macro language for any software package that includes an ARexx interface. It's both powerful and easy-to-learn, and is well documented in a 150-page manual. ................................. Only $49.95 (plus $2 shipping) WShell is a much-enhanced but highly compatible CLI replacement that offers aliases, built-in and resident commands, concurrent command piping (as in pgm1 | pgm2 | ... | pgmN), extended prompt/window titlebar fields, transparent support for REXX macro programs, an "implicit" CD command, script-bit support, and lots of other features. Isn't it time you put some mussel into your command environment? Just 50 clams (+ $2 shipping) ** better dealers are those that stock ARexx and WShell. ----- Further Notes ----- ConMan also accepts window specifications in the form "CON:w20480", where the hex digits following the "w" are the absolute address of an Intuition window pointer. This allows you to attach a console handler to a window in a multitasking-safe way (unlike the methods that require setting a field in the DOS device list). If you're writing in C, you could use the following sequence to open a window and attach a DOS console to it: window = OpenWindow(&newwindow); /* get a window */ sprintf(buffer,"CON:W%x",window); /* build the name string */ file = Open(buffer,MODE_OLDFILE); /* open a console stream */ You can open a console window on a custom screen by passing the hex address of the screen preceded by an "S" in the specification string, as in "CON:S123abc/10/10/300/100/MyWindow." ConMan will accept "S*" as a shorthand notation for the frontmost screen, so a specification like "CON:S*/0/0/300/100/Front" would open on whichever screen was in front. In addition, ConMan now supports superbitmap windows as well. The bitmap structure is passed as a "B" followed by the hex address, as for example "CON:B123ABC/0/0/300/100/Super!". The console device currently has some bugs related to using superbitmaps (for example, the cursor disappears), but this feature may be handy anyway. Other Names. ConMan is actually several DOS handlers rolled into one, and it selects the desired mode of operation by looking at the name used to open it. The four special names recognized are CND:, CNX:, PIP:, and RAW:, and all other names are considered equivalent to CON:. In order to use ConMan under any name other than CON:, you'll need to add one or more of the supplied mountlist entries to your DEVS:mountlist file and then issue the "mount" command. For example, to define ConMan as the CNC: device, add the CNC: entry to DEVS:mountlist and issue "mount CNC:". Once you've done this, you can get a ConMan window by specifying a name like CNC://640/100/MyWindow. This allows the CON: definition to be left intact, in case there are any incompatibilities between ConMan and your existing software (but please let me know of any problems!) Warning: DO NOT USE the ARP mount command to mount ConMan --- it has a known bug that causes the console handler to open up in RAW mode. The CND: handler, new to V1.3, operates in a mode that allows invisible (non-blocking) type-ahead. After the line you enter has been read, any further input is not displayed until the command shell (or other software) again reads from the console. This gives unimpeded access to whatever software is writing to the console. Example: NewCLI "CND://640/100/VAX Head!" The CNX: handler is also new to V1.3, and provides extensibility by allowing you to specify any EXEC-level device for the console display. The display device name and unit are passed immediately following the handler name, as in "CNX:device-name/unit". For example, you could specify the serial device as "CNX:serial.device/0", providing an AUX: handler with full line editing and command history. The display device must support the standard ANSI control sequences on read and write. Example: NewCLI CNX:serial.device/0 ConMan is also a pipe-handler responding to the name PIP:NNNN, where NNNN is the "capacity" of the pipe. It must be opened using a private packet called ACTION_DOUBLE (value 2000L), and the filehandle you get from a call to Open("PIP:",2000) counts for two and so can be cloned by your program. After allocating a filehandle structure (using the AmigaDOS memory conventions), just copy the filehandle from Open() into the new structure --- and don't forget to Close() both of them! My WShell command shell uses the ConMan PIP: device as its pipe handler. Those of you with AmigaDOS 1.3 (but not yet blessed with WShell) will appreciate the sly inclusion of the NEWCON: mountlist entry. Break Signals. Break signals are generated by typing a control-C, D, E, or F and can be delivered to any task that has opened, read from, or written to ConMan. The break-signal handling in ConMan is much more sophisticated than that in the standard CON: handler, and additional improvements have been made in V1.3 to eliminate the possibility of signalling a non-existent task. ConMan is able to signal a task that has only read from or written to the console -- even if it hasn't opened it -- by holding the break event until a read or write request arrives. In addition to the break signals generated by user input, ConMan will send a control-C break to any task that continues to write to the handler when it's trying to close. ConMan is in such a "closing" state after the close gadget on a window has been hit, or if it is a PIP: pipe with only one open remaining. This automatic "break-on-write" provides a way of propagating a signal back through a series of piped programs. Auto-break can be disabled by specifying the -disable option to the ConMan command. Keymapping. ConMan supports the Amiga's keymapping facility, which allows you to reassign the editing functions to the keys of your choice. To do this, you must first construct a keymap either in assembly language or with the help of a keymap editor. You can then load the keymap using the SetMap program on your WorkBench disk. By default SetMap makes a keymap global; if you want to use a special keymap from just one CLI, you can use the included KeyMap command to define the desired map. KeyMap with no arguments will display a list of the available keymaps. ----- What Next? ----- Most of the requested features have been added to ConMan now, but there are a still a couple of suggestions being considered. Several users have requested more flexible keymapping features to allow function keys to be redefined on the fly. Another possibility is an improved "iconify" state, so that the window can be double-clicked back to the former size. ----- Bugs ----- All known bugs have been fixed in this release, so you should find it to be very reliable. If you do find a problem, PLEASE report it so I can fix it!! Previous versions of ConMan (before 1.3) exhibited a problem associated with very rapid toggling between the "shrink" and "zoom" window states. This problem has been fixed by adding a further level of interlocking, and the F1/F2 keys should now be completely safe. Furthermore, the underlying cause of the window-sizing problem will be fixed in version 1.4 of Intuition, so there should be no more trouble from this source. One warning still applies: the console device exhibits serious problems with windows below some minimum size. Opening windows of certain sizes (e.g. con:0/0/10/20/) may cause the machine to crash, whether or not ConMan is active. For these reasons, I strongly urge you avoid console windows smaller than 80X25 or so. ----- Acknowledgements ----- Special thanks to John Toebes and the Software Distillery for lots of great suggestions, to Jeff White for the handsome icons, and to the many contributors who made ongoing development and improvements possible. -- Bill Hawes (September 28, 1988)